home *** CD-ROM | disk | FTP | other *** search
/ Windows Expert / Windows Expert.iso / windownt / queue.zip / QUEUE / README.TXT < prev   
Text File  |  1992-11-07  |  5KB  |  141 lines
  1.  
  2. Windows NT does not provide queues.  However, several people who were
  3. used to using the DosQueue functions of OS/2 have asked for this
  4. functionality -- so here it is.
  5.  
  6. In general, this implementation relies upon shrmem.dll, the shared
  7. memory handling dll I wrote earlier.  I have also changed the syntax
  8. for some of these functions.  I hope that the newer functions will be
  9. easier to use.
  10.  
  11. Their are two main differences in the use/syntax presented here from
  12. the original.  The first relates to the use of shared memory in
  13. combination with queues.
  14.  
  15. An OS/2 algorithm for writing to a queue looks like this:
  16.     OpenQueue() and remember queue owner PID.
  17.     Allocate shared memory
  18.     Turn shared memory seg into a pointer
  19.     place data in shared memory
  20.     Give the seg to the owner of the queue, unless I own the
  21.         queue.
  22.     WriteQueue, giving a pointer, length, priority, and event code.
  23.  
  24. The OS/2 queue reader then:
  25.     ReadQueue, getting the writer id and event code in a structure,
  26.         the priority in a seperate variable, and the pointer/length
  27.         in two others.
  28.     Free shared memory
  29.  
  30. =====================
  31. The useage here changes slightly:
  32. An algorithm for writing to a queue looks like this:
  33.     OpenQueue()
  34.     Allocate shared memory
  35.     Lock shared memory
  36.     place data in shared memory
  37.     Unlock Shared memory
  38.     WriteQueue, giving a shared memory handle, priority, and event code.
  39.  
  40. The queue reader then:
  41.     ReadQueue, all info (see queue_elem below) provided in a
  42.         structure.
  43.     Lock/Use/Unlock shared memory
  44.     Free shared memory
  45.  
  46. The applications qsrv.exe and qclient.exe contain my test routines.
  47.  
  48. ====================================================
  49. API specs
  50. ====================================================
  51.  
  52. DWORD CreateQueue( PHQUEUE phq, int fQueueOrder, LPTSTR pszName);
  53.  
  54. Create a queue.  Anonymous queues not allowed.  The name may begin
  55. with \queues\ for compatibility reasons, but can not contain any
  56. other '\\' characters.
  57.  
  58. fQueueOrder one of {QUE_FIFO, QUE_LIFO, QUE_PRIORITY}
  59.  
  60. return is 0 on success or:
  61.     QUE_INVALID_NAME
  62.     QUE_NO_MEMORY
  63.     or some other result obtained from GetLastError()
  64.  
  65. DWORD CloseQueue( HQUEUE hq);
  66.  
  67. Close a queue.
  68.  
  69. return is 0 on success or:
  70.     QUE_INVALID_HANDLE
  71.  
  72. DWORD OpenQueue(LPDWORD ppid, PHQUEUE phq, LPTSTR pszName);
  73.  
  74. Open a queue named pszName.  The Id of the process which created the
  75. queue is returned in ppid.
  76.  
  77. return is 0 on success or:
  78.     QUE_INVALID_NAME
  79.     QUE_NO_MEMORY
  80.     QUE_NAME_NOT_EXIST
  81.     or some other result obtained from GetLastError()
  82.  
  83. DWORD WriteQueue(HQUEUE hq, DWORD dwEventCode, DWORD dwShrHandle, DWORD dwPriority);
  84.  
  85. Write to queue hq with dwEventCode, dwShrHandle, and dwPriority
  86. values.  Note that all values are passed as is, so you could use this
  87. as a 3 DWORD message if you wished.  Priority is 0 lowest, ascending
  88. upwards.
  89.  
  90. return is 0 on success or:
  91.     QUE_INVALID_HANDLE
  92.     QUE_NO_MEMORY
  93.  
  94. DWORD ReadQueue(HQUEUE hq, PQ_ELEMENT pqe, int iElement, BOOL fWait);
  95.  
  96. Read element iElement.  A negative iElement is treated as 0. 
  97. iElement should be either 0 or the result of a PeekQueue call.
  98.  
  99. if fWait is true, this call will block indefinitely on a handle to an
  100. event until something is in the queue.  If you want finer control
  101. that this, use GetQueueEventHandle() to get the handle yourself.
  102.  
  103. Data is returned in the Q_ELEMENT structure:
  104. typedef struct _queue_elem {
  105.     DWORD  dwWriterId;
  106.     DWORD  dwShrHandle;
  107.     DWORD  dwEventCode;
  108.     DWORD  dwPriority;
  109.  
  110. } Q_ELEMENT;
  111. typedef Q_ELEMENT *PQ_ELEMENT;
  112.  
  113. return is 0 on success or:
  114.     QUE_ELEMENT_NOT_EXIST
  115.     QUE_EMPTY
  116.     QUE_INVALID_HANDLE
  117.     QUE_INVALID_NAME
  118.     QUE_NO_MEMORY
  119.     or some other result obtained from GetLastError()
  120.  
  121. HANDLE GetQueueEventHandle( HQUEUE hqueue);
  122. return is 0 on failure, or a Event queue you can wait on.
  123. The handle to the Event will be in the Signaled state (Wait's will
  124. not block ) while data is in the queue.
  125.  
  126. DWORD PeekQueue(HQUEUE hq, PQ_ELEMENT pqe, int *piElement, BOOL fWait);
  127.  
  128. This call doesn't remove the queue element from the queue.  Further,
  129. you pass in a queue element (-1 means get first element, anything
  130. else will try to find queue element (*piElement)+1 returning same
  131. in piElement.  Other than that, it is the same as ReadQueue.
  132.  
  133. return is 0 on success or:
  134.     QUE_ELEMENT_NOT_EXIST
  135.     QUE_EMPTY
  136.     QUE_INVALID_HANDLE
  137.     QUE_INVALID_NAME
  138.     QUE_NO_MEMORY
  139.     or some other result obtained from GetLastError()
  140.  
  141.